本地化搜索与分析引擎 & Skill 技能配置
你会学到什么
Claude Code 内置了 WebSearch 工具，但它依赖海外 API、有速率限制、搜索结果不够可控。本节教你搭建一套本地化搜索系统：用 Docker 跑 SearXNG 聚合搜索引擎，用 Python 写 MCP 服务器对接 Claude Code，再配一个 Skill 让 AI 自动完成「搜索 → 爬取 → 整理 → 输出报告」的全流程。
学完本节你能做到：在 Claude Code 里说一句"搜索 Vue 3 最新更新"，AI 自动调用你的本地搜索引擎，自主搜索、爬取官方 changelog 和深度文章、交叉验证信息真实性，最后整理成结构化报告——全程无需人工干预。
为什么要自己搭搜索？
AI 的知识是有截止日期的
大语言模型的训练数据有截止时间，而且知识不能实时更新。你会发现一个现象：问 AI "Vue 3.5 有什么新特性"，它回答得头头是道；问"2026 年最新的构建工具是什么"，它要么告诉你"我无法访问互联网"，要么给一个过时的答案。正因如此，OpenAI 在 2024 年就给 ChatGPT 加上了联网搜索：先通过网络搜索一批网页，把内容作为上下文再交给大模型输出，模型就具备了实时信息能力——这也是我们本节要在本地复刻的思路。
Claude 的训练数据截止时间随版本迭代持续推后，但边界始终存在：
- Vue 3.5 发布于 2024 年 9 月 → 模型知道
- Vite 7 于 2025 年 7 月发布、Vue 3.6 的 Vapor Mode 2026 年才进入 RC → 旧版本模型可能不熟悉
- 你的项目的 Bug 报告 → 模型当然也不知道
在 AI 辅助开发中，信息过时 = 给出错误建议，后果可能是选了一个已经废弃的 API、踩了一个已经被修复的 Bug。
Claude Code 内置搜索够用吗？
Claude Code 自带了 WebSearch 工具，能联网搜索，但需要订阅才可用，而且有几个实际限制：
| 限制 | 具体表现 |
|---|---|
| 依赖海外 API | 国内网络不稳定，经常超时 |
| 订阅门槛 | 非 Claude Code 订阅用户用不了该功能 |
| 速率限制 | 搜索次数有限，连续搜索会被限流；各类 Coding Plan 自带的搜索同样有次数上限 |
| 结果不可控 | 返回的是摘要，无法指定搜索引擎或语言 |
| 不能连续爬取 | 能爬取部分网页，但不能连续爬取，连续爬取同样受限 |
| 无状态 | 每次搜索独立，不能基于上次结果深入搜索 |
举个例子：你让 Claude Code 帮你调研"2025 年前端构建工具对比"。用内置搜索，你会得到 10 条摘要。但你没法让它爬取每篇文章的完整内容，也没法让它针对某个子话题继续深入搜索。
现有的搜索方案对比
市场上已有多种"AI + 搜索"的方案，各有利弊：
| 方案 | 代表产品 | 优点 | 缺点 | 费用 |
|---|---|---|---|---|
| AI 原生搜索 | Perplexity、ChatGPT 搜索 | 体验好，开箱即用 | 不能集成到开发工具中 | $20/月起 |
| 搜索 API | Brave Search API、SerpAPI | 稳定可靠 | 按次计费，费用不可控 | $5-50/月 |
| 浏览器插件 | Monica、Sider | 不用切换工具 | 无法自动化搜索流程 | $10-20/月 |
| 自建本地搜索 | SearXNG + MCP（本节方案） | 免费无限制、可定制、集成到 Claude Code | 需要一次性配置 | 免费 |
自建方案的核心优势不是"省钱"——而是可控性。你可以控制用哪些搜索引擎、搜索结果怎么过滤、内容怎么爬取和整理。当 AI 能自主决定"搜什么、怎么搜、结果怎么用"的时候，搜索就从一个被动工具变成了 AI 的主动能力。
技术方案选型：为什么是 SearXNG + MCP + Skill
搜索引擎选型
为什么不直接用 Google API 或 DuckDuckGo API？
| 方案 | 问题 |
|---|---|
| Google Custom Search API | 免费额度只有 100 次/天，超出 $5/1000次 |
| Bing Search API | 需要 Azure 账号，免费额度也很有限 |
| DuckDuckGo API | 没有官方 API，需要逆向工程（不稳定） |
| SerpAPI | 商业产品，$50/月起 |
| SearXNG（自建） | 免费、无限量、聚合 70+ 搜索引擎、支持 JSON API |
SearXNG 是一个开源的本地化聚合搜索引擎（GitHub 39k+ star（2026-11-07 核实），版本按日期滚动发布，2026-10 已到 2026.10.x），一个请求同时查询 Google、Bing、DuckDuckGo、Wikipedia 等几十个引擎，返回去重后的合并结果。它原生支持 JSON API，对本地对接 AI 模型非常友好；通过 Docker 一行命令部署，本地运行，没有 API 调用费用，没有速率限制。可以把它理解为"部署在自己电脑上的聚合搜索网站"，还能按分类（综合/新闻/图片等）分别响应不同引擎的结果——这正是它能方便集成进本地 AI 服务的原因。
为什么用聚合搜索而不是单一引擎？因为不同引擎擅长不同内容：
- Google：技术文档、英文内容最全
- Bing：图片和视频搜索优秀
- DuckDuckGo：隐私搜索，不追踪
- Wikipedia：权威的百科信息
- GitHub：代码和项目搜索
聚合搜索一次请求等于同时用了所有引擎，信息覆盖面远超单一来源。
工具对接协议选型：为什么是 MCP
Claude Code 支持三种方式扩展能力：Commands、Skills、MCP Servers（第3章讲过）。
搜索能力适合用 MCP 而不是 Skills 或 Commands，原因很直接：
| 扩展方式 | 适合场景 | 为什么搜索不适合 |
|---|---|---|
| Command | 一次性操作（如 /commit） | 搜索是被动的、被 AI 主动调用的，不是用户手动触发 |
| Skill | 指导 AI 行为的提示词 | Skill 不能定义新工具，只能教 AI 用已有工具 |
| MCP Server | 给 AI 提供新工具 | 搜索是"新能力"，需要定义 search_web、crawl_url 等工具 |
MCP 的本质是给 AI 装上"新手"。AI 看到用户的问题，自己决定要不要搜索、搜什么关键词、爬哪些页面。这个决策过程需要 AI 能直接调用工具，而不是等用户下命令。
策略层选型：为什么还需要 Skill
有了 MCP 工具，AI 就会搜索了吗？不完全会。看看没有 Skill 时会发生什么：
用户：帮我调研 2025 年 React Server Components 的成熟度
没有 Skill 的 AI：
1. 调用 search_web("React Server Components 2025")
2. 拿到 10 条摘要
3. 基于摘要直接回答（信息不够深入）
有 Skill 的 AI：
1. 分析问题：这是一个技术成熟度评估，需要多方信息
2. 生成多个搜索词："RSC production ready 2025"、"React Server Components issues"
3. 搜索 → 评估结果相关性 → 爬取 3-5 篇深度文章
4. 发现信息缺口 → 补充搜索 "RSC vs SSR comparison"
5. 综合所有信息，输出结构化报告
text
Skill 就是搜索的"经验"。MCP 提供工具（能搜索），Skill 提供策略（怎么搜、搜完怎么整理）。两者配合才是完整的解决方案。
三层架构的分工
理解了上面三个选型决策，整个架构就清晰了：
┌─────────────────────────────────────────┐
│ Skill 层（策略） │
│ 教 AI：什么时候搜、搜什么、怎么整理结果 │
├─────────────────────────────────────────┤
│ MCP 层（工具） │
│ 定义 search_web、crawl_url 等工具接口 │
├─────────────────────────────────────────┤
│ 基础设施层（数据） │
│ SearXNG 搜索引擎、crawl4ai 爬虫 │
└─────────────────────────────────────────┘
text
这三层各司其职，互不耦合：
- 换搜索引擎？改基础设施层，Skill 和 MCP 不用动
- 加新的工具（如截图、PDF 导出）？改 MCP 层，Skill 和基础设施不用动
- 调整搜索策略（如优先搜中文内容）？改 Skill 层，其他不动
这就是为什么本节要讲 SearXNG（基础设施）、MCP（工具对接）、Skill（搜索策略）三个东西——它们是分层解耦的，缺一不可。
整体架构
先看全貌，再看每一步怎么做：
用户提问 → Claude Code → Skill（决定搜索策略）
↓
MCP 服务器（Python）
┌─────┼─────┐
↓ ↓ ↓
SearXNG crawl4ai Qdrant（可选）
（搜索） （爬取） （向量存储）
↓
整理输出 Markdown 报告
text
核心组件：
| 组件 | 作用 | 是否必需 |
|---|---|---|
| SearXNG | 聚合搜索引擎，同时查询 Google/Bing/DuckDuckGo 等 | 必需 |
| crawl4ai | 爬取网页内容，转为 Markdown | 必需 |
| Qdrant | 向量数据库，支持语义搜索 | 可选（进阶） |
| Meilisearch | 全文搜索引擎 | 可选（进阶） |
| MCP Server | Python 服务，将搜索能力暴露给 Claude Code | 必需 |
| Skill | 指导 AI 如何使用搜索工具的提示词 | 必需 |
最小配置只需要 SearXNG + MCP Server + Skill，三个东西就能跑起来。
实测对比：local-search vs 内置搜索
配置完成后，讲师在课上做了一组同题对比，很能说明差距。
local-search 的完整调研过程
对 Claude Code 说"用 local-search 搜索一下 Vue 3 最新的更新内容"，AI 的自主行为链是：
- 先后发起 3 次不同关键词的搜索（Skill 决定搜索策略）
- 用 MCP 工具处理结果，筛出高相关度条目
- 开始爬取详细内容——先是搜索摘要，再深入抓取官方 changelog、官方博客和深度技术文章
- 中途自我反思：这些信息是否足够？是否真实？——它不会默认"网上发布的就是真的"，会交叉验证
- 产出结构化报告，附发布页链接可点击跳转
全程零人工干预。这种多轮搜索+爬取产生的长上下文，整合时用到了 claude-mem（下一节配置）。
报告里给出的信息（课程录制时）：Vue 3.5 系列持续迭代（当时 3.5.33），3.6 处于 alpha/beta 阶段、预计 2026 年四季度发布；3.5 的重大更新包括响应式系统重构（reactive props destructure）、SSR 改进、useTemplateRef、watch 清理回调注册；3.6 的前瞻是 Vapor Mode——绕过虚拟 DOM、把模板编译为直接的 DOM 操作（类似 Svelte 的编译策略），更快首次渲染、更低内存占用；defineModel 转正、defineOptions 宏、Vite/Nuxt/Pinia 生态更新。而问模型"你的知识截止到什么时候"，回答是 2025 年初——搜索把模型的认知推进了一年多。
2026-11-07 校对：Vue 3.5 线最新为 3.5.45（Latest），3.6.0 已到 rc.14，Vapor Mode 功能完备（feature-complete）、按组件选择性启用
<script setup vapor>，稳定版尚未发布（截至 2026-11 仍在 RC）。（2026-11-07 核实）
同题对比：Gemini 内置搜索
换 Gemini CLI（Coding Plan 自带的 web search 工具），禁止使用 local-search，回答同样的问题：它调用搜索 API 只抓到了掘金、dev.to 等约 3 个来源，MCP 工具只调用了 3 次（有使用限制时模型会主动少调用）——给出的结论（watch 方法、Teleport 组件改进、SSR 性能、3.6 beta、Vapor Mode、defineExpose、Suspense 等）大方向不差，但信息来源太窄。
而 local-search 让 AI 打印历史搜索记录，来源约 25 个：Vue 官方文档、GitHub、掘金、知乎、Vue School 等，覆盖面和结论完整度明显更高：
| 维度 | Gemini 内置搜索 | local-search |
|---|---|---|
| 信息来源 | 约 3 个网站 | 约 25 个来源（官方文档/GitHub/掘金/知乎/Vue School…） |
| 工具调用 | 约 3 次（受配额约束） | 搜索 3 轮 + 多轮爬取，不受限 |
| 过程 | 摘要提炼后直接回答 | 搜索→爬取→反思→补搜→验证真实性 |
| 人工干预 | 无 | 无 |
这就是"可控性"的具体体现：不省钱，省的是信息差。
第一步：Docker 环境与 SearXNG
安装 Docker
macOS 安装 Docker Desktop（Windows 直接官网下载对应版本）：
# 检查是否已安装
docker --version
# 未安装的话，去官网下载
# https://www.docker.com/products/docker-desktop
bash
Mac 上如果嫌 Docker Desktop 太重，可以用轻量替代方案 OrbStack（orbstack.dev）——同样能管理容器，资源占用小得多，讲师本人用的就是这个方案。
国内网络直连 Docker Hub 拉镜像经常超时，需要配置镜像加速：注册阿里云容器镜像服务（免费），每个账号都有专属的加速地址，按官方指引填进 Docker 的 registry-mirrors 配置即可。另外 SearXNG 官方镜像同步发布在 GHCR（ghcr.io/searxng/searxng），Docker Hub 限流时可以直接换用这个源。
安装后确认 Docker 在运行：
docker info
bash
启动 SearXNG
一行命令启动（挂载配置目录和缓存目录，容器重建不丢配置）：
docker run -d \
--name searxng \
--restart unless-stopped \
-p 8080:8080 \
-v ./searxng:/etc/searxng \
-v ./data:/var/cache/searxng \
-e BASE_URL=http://localhost:8080 \
searxng/searxng:latest
bash
两个挂载点的含义：/etc/searxng 是配置文件（settings.yml 等），/var/cache/searxng 是持久化数据（favicon 缓存等）——这是官方文档明确建议挂载的两个卷。
验证是否成功：
# 浏览器打开或 curl 访问
curl http://localhost:8080
# 测试搜索 API
curl "http://localhost:8080/search?q=vue3&format=json"
bash
看到 JSON 返回就说明 SearXNG 跑起来了。它默认聚合了 Google、Bing、DuckDuckGo、Wikipedia 等几十个搜索引擎，无需额外配置。
Web UI 速览与引擎选择
浏览器打开 http://localhost:8080 就是 SearXNG 的聚合搜索页面。搜索任何关键词，结果页会标注每条结果来自哪个引擎，还能点击"快照"直接查看网页缓存——这就是"聚合"最直观的感受。用过聚合搜索类网站的同学对这套界面不会陌生，区别是它现在跑在你自己机器上。
进入"首选项"可以按分类开关搜索引擎：
- 综合搜索：Google、Bing、DuckDuckGo、Wikipedia、GitHub 等，建议全开
- 国内引擎：搜狗、夸克、百度等也内置支持，但搜索质量普遍偏差，讲师实测不推荐开启
- 垂直分类：新闻、图片、视频、IT、科学等各有独立引擎列表
这套分类开关同样作用于 JSON API 的返回来源，方便集成到本地 AI 服务时按需收窄。
课程演示中的踩坑实录
讲师课上用简化版 compose 文件演示部署（docker compose -f docker-compose.searxng.yml up -d），实际踩了三个坑，你大概率也会遇到：
- 端口冲突：首次启动失败，报端口被占用——本地已有服务占用了 80 端口。改用 8081 端口映射后正常。看到
Container searxng-test Started即启动成功，可用docker ps | grep searxng确认，浏览器访问localhost:8081验证。 - 首次进入报基础配置警告：可能是容器网络不通（代理没配好），也可能是界面语言不对——在首选项里把语言切到中文，再搜一次"Vue 3.5"验证网络连通。
- 删除重来：
docker compose -f docker-compose.searxng.yml down即可完全移除服务。
课程资料文件夹提供了最终使用的 docker-compose 文件（含向量数据库、缓存等配套服务，供 local-search 后续使用）。跟学演练请用最终版，不要用演示用的简化版。如果跑不通，直接把 compose 文件丢给 Claude Code："按照这个 docker-compose，结合我本地的环境，帮我配置并启动对应的服务"——让 AI 排查环境问题，这是 AI 时代做技术的人应有的基础能力。
代理配置（国内网络必需）
国内网络直接用 SearXNG 访问 Google/Bing 会被墙。需要给 SearXNG 容器配置代理。
假设你的代理跑在本机 7890 端口（Clash/V2Ray 默认端口）：
# 先停掉之前的容器
docker stop searxng && docker rm searxng
# 带代理启动
docker run -d \
--name searxng \
--restart unless-stopped \
-p 8080:8080 \
-e BASE_URL=http://localhost:8080 \
-e HTTP_PROXY=http://host.docker.internal:7890 \
-e HTTPS_PROXY=http://host.docker.internal:7890 \
-e http_proxy=http://host.docker.internal:7890 \
-e https_proxy=http://host.docker.internal:7890 \
--add-host=host.docker.internal:host-gateway \
searxng/searxng:latest
bash
关键参数解释：
| 参数 | 作用 |
|---|---|
host.docker.internal | Docker 容器访问宿主机的特殊域名 |
--add-host=host.docker.internal:host-gateway | 确保容器能解析这个域名 |
7890 | 你本机的代理端口，改成你自己的 |
如果你用的是 Clash Verge 的 TUN 模式（全局代理），可以不配代理参数——所有流量已经走代理了，再配一层反而会双重代理导致失败。
验证代理是否生效：
# 搜索一个需要翻墙的关键词
curl -s "http://localhost:8080/search?q=latest+vue+3+features&format=json" | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'结果数: {len(d.get(\"results\", []))}')"
bash
用 docker-compose 管理（推荐）
创建 docker-compose.yml：
services:
searxng:
image: searxng/searxng:latest
container_name: searxng
ports:
- "8080:8080"
environment:
- BASE_URL=http://localhost:8080
# 按需取消注释，配置代理
# - HTTP_PROXY=http://host.docker.internal:7890
# - HTTPS_PROXY=http://host.docker.internal:7890
volumes:
- ./searxng:/etc/searxng
- ./data:/var/cache/searxng
restart: unless-stopped
extra_hosts:
- "host.docker.internal:host-gateway"
# 以下为可选服务，初次配置可以不启用
# 向量数据库（语义搜索）
# qdrant:
# image: qdrant/qdrant:latest
# container_name: qdrant
# ports:
# - "6333:6333"
# volumes:
# - qdrant_data:/qdrant/storage
# restart: unless-stopped
# 全文搜索引擎
# meilisearch:
# image: getmeili/meilisearch:latest
# container_name: meilisearch
# ports:
# - "7700:7700"
# environment:
# - MEILI_MASTER_KEY=masterKey123
# volumes:
# - meilisearch_data:/meili_data
# restart: unless-stopped
# volumes:
# qdrant_data:
# meilisearch_data:
yaml
启动：
docker compose up -d
bash
两个补充说明：官方仓库的 compose 模板（container/docker-compose.yml）还带了一个 valkey 服务（Redis 的开源分支），用于公网部署时的限流与防爬虫——本地自用关闭 limiter 即可，不需要它。另外 SearXNG 采用按日期滚动的版本号（如 2026.10.4），latest tag 会持续向前；在意环境可复现的话，可以把镜像钉住某个日期版本。
自定义 SearXNG 配置
挂载 ./searxng/settings.yml 可以深度定制搜索引擎行为。常见配置：
# searxng/settings.yml 关键配置
search:
safe_search: 0 # 关闭安全搜索
default_lang: "auto" # 自动检测语言
formats:
- html
- json # 必须开启 JSON 格式，MCP 需要用
server:
port: 8080 # 容器内监听端口（与上面的端口映射一致）
limiter: false # 关闭速率限制（本地用不需要）
secret_key: "随机字符串" # 随便填一个
outgoing:
request_timeout: 10.0
max_request_timeout: 15.0
yaml
SearXNG 默认就开启了大量搜索引擎（Google、Bing、DuckDuckGo、Wikipedia、GitHub 等），开箱即用不需要手动配置引擎列表。
第二步：创建 MCP 服务器
MCP（Model Context Protocol）是 Claude Code 与外部工具通信的协议。我们需要写一个 Python 服务，把 SearXNG 的搜索能力暴露给 Claude Code。
项目结构
local-search-mcp/
├── src/
│ └── local_search_mcp/
│ ├── __init__.py
│ ├── main.py # MCP 入口，注册工具
│ ├── config.py # 配置管理
│ └── tools/
│ ├── __init__.py
│ ├── search.py # 搜索工具
│ └── crawl.py # 爬取工具
├── pyproject.toml # 项目依赖
├── docker-compose.yml
└── searxng/
└── settings.yml
text
pyproject.toml — 最小依赖
[project]
name = "local-search-mcp"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
"mcp>=0.9.0",
"httpx>=0.27.0",
"crawl4ai>=0.3.0",
]
[project.scripts]
local-search-mcp = "local_search_mcp.main:run"
toml
只需要三个核心依赖：mcp 是协议库，httpx 请求 SearXNG API，crawl4ai 爬取网页。
main.py — MCP 服务器核心
"""本地搜索 MCP 服务器 - 最小可用版本"""
import asyncio
import httpx
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
SEARXNG_URL = "http://localhost:8080"
app = Server("local-search-mcp")
@app.list_tools()
async def list_tools() -> list[Tool]:
"""列出可用的 MCP 工具"""
return [
Tool(
name="search_web",
description="使用 SearXNG 搜索引擎搜索网页，返回标题、URL和摘要",
inputSchema={
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "搜索关键词",
},
"limit": {
"type": "number",
"description": "返回结果数量，默认10",
"default": 10,
},
},
"required": ["query"],
},
),
Tool(
name="crawl_url",
description="爬取指定URL的网页内容，返回Markdown格式文本",
inputSchema={
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "要爬取的网页URL",
},
},
"required": ["url"],
},
),
]
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
"""处理工具调用"""
if name == "search_web":
query = arguments["query"]
limit = arguments.get("limit", 10)
async with httpx.AsyncClient(timeout=15.0) as client:
resp = await client.get(
f"{SEARXNG_URL}/search",
params={
"q": query,
"format": "json",
"pageno": 1,
},
)
data = resp.json()
results = data.get("results", [])[:limit]
# 格式化搜索结果
output_lines = [f"## 搜索结果: {query}\n"]
for i, r in enumerate(results, 1):
title = r.get("title", "无标题")
url = r.get("url", "")
snippet = r.get("content", "")
output_lines.append(f"{i}. **{title}**\n URL: {url}\n {snippet}\n")
return [TextContent(type="text", text="\n".join(output_lines))]
elif name == "crawl_url":
url = arguments["url"]
# 使用 crawl4ai 爬取
try:
from crawl4ai import AsyncWebCrawler
async with AsyncWebCrawler() as crawler:
result = await crawler.arun(url=url)
content = result.markdown[:5000] # 截断防止过长
return [TextContent(type="text", text=f"## {url}\n\n{content}")]
except ImportError:
# fallback: 用 httpx 直接获取
async with httpx.AsyncClient(timeout=15.0) as client:
resp = await client.get(url, follow_redirects=True)
return [TextContent(type="text", text=resp.text[:5000])]
def run():
"""启动 MCP 服务器"""
asyncio.run(stdio_server(app).serve())
if __name__ == "__main__":
run()
python
这段代码做了三件事：
- 注册两个工具：
search_web（搜索）和crawl_url（爬取） search_web调用 SearXNG 的 JSON API 获取搜索结果crawl_url用 crawl4ai 爬取网页内容转为 Markdown
安装与运行
# 创建项目目录
mkdir -p ~/Projects/local-search-mcp/src/local_search_mcp
# 用 conda 管理环境
conda create -n local-search-mcp python=3.11 -y
conda activate local-search-mcp
# 安装依赖
cd ~/Projects/local-search-mcp
pip install -e .
bash
验证 MCP 服务器能跑：
# 检查能否启动
python src/local_search_mcp/main.py
# 按 Ctrl+C 退出，没报错就行
bash
第三步：配置 Claude Code 连接 MCP
.mcp.json 配置
在项目根目录或 ~/.mcp.json（全局）创建配置：
{
"mcpServers": {
"local-search": {
"command": "/你的路径/miniconda3/envs/local-search-mcp/bin/python",
"args": ["你的路径/local-search-mcp/src/local_search_mcp/main.py"],
"env": {
"SEARXNG_URL": "http://localhost:8080"
}
}
}
}
json
找到你的 Python 路径：
conda activate local-search-mcp
which python
# 输出类似: /Users/xxx/miniconda3/envs/local-search-mcp/bin/python
bash
也可以用 uvx 方式（不需要 conda）：
{
"mcpServers": {
"local-search": {
"command": "uvx",
"args": [
"--from",
"/你的路径/local-search-mcp",
"local-search-mcp"
],
"env": {
"SEARXNG_URL": "http://localhost:8080"
}
}
}
}
json
验证 MCP 连接
重启 Claude Code 后，检查 MCP 工具是否可用：
在 Claude Code 中输入：
请用 local-search 的 search_web 工具搜索 "Vue 3.5 新特性"
text
如果返回搜索结果，说明 MCP 连接成功。
第四步：创建 Skill — 让 AI 懂得如何搜索
MCP 只提供了工具，但 AI 不知道什么时候该搜索、搜索结果怎么整理。Skill 就是教 AI 怎么用这些工具的提示词。
Skill 文件结构
~/.claude/skills/local-search/
└── SKILL.md
text
SKILL.md — 搜索技能提示词
将以下内容保存为 ~/.claude/skills/local-search/SKILL.md：
frontmatter
--- name: local-search description: 使用本地搜索引擎进行信息搜索和分析，自动整理输出结构化报告 ---text
正文部分：
# 本地搜索技能
你是一个搜索助手，能够使用 local-search MCP 工具进行网络搜索和内容爬取。
## 可用工具
| 工具 | 用途 | 何时使用 |
|------|------|----------|
| search_web | SearXNG 搜索 | 需要搜索信息时 |
| crawl_url | 爬取网页内容 | 需要获取详细内容时 |
## 搜索流程
### 第1步：理解问题，生成搜索词
分析用户问题，生成 1-3 个搜索查询。优先用中文搜索中文内容，用英文搜索技术文档。
示例：
- 用户问 "Vue 3.5 有什么新特性" → 搜索 "Vue 3.5 new features" 和 "Vue 3.5 新特性"
- 用户问 "Vite 和 Webpack 哪个好" → 搜索 "Vite vs Webpack comparison 2025"
### 第2步：执行搜索
调用：search_web(query="搜索词", limit=10)
### 第3步：评估结果
检查搜索结果的相关性：
- 7个以上结果相关 → 直接爬取排名前 3-5 的 URL
- 3-6 个相关 → 换个搜索词再搜一次
- 不到 3 个相关 → 重新组织搜索词
### 第4步：爬取详细内容
对最相关的 3-5 个结果，调用：crawl_url(url="https://...")
### 第5步：整理输出
将搜索和爬取的信息整理成结构化报告：
**技术主题格式：** 概述 → 核心内容（分点说明）→ 代码示例（如有）→ 参考链接
**对比分析格式：** 对比表格 → 各方案优劣 → 推荐场景
**调研报告格式：** 背景与现状 → 关键发现 → 趋势总结 → 数据来源
## 搜索策略
- **技术问题**：优先搜 GitHub、官方文档、Stack Overflow
- **新闻资讯**：搜索多个来源交叉验证
- **对比分析**：分别搜索各方案，再搜 "A vs B" 类对比文章
- **中文内容**：搜索时加 "site:zhihu.com" 或 "site:juejin.cn" 限定来源
## 注意事项
- 每个事实性结论必须附上来源 URL
- 信息不确定时明确标注
- 爬取内容超过 5000 字时自动截断，重点提取关键信息
text
安装 Skill
将 SKILL.md 放到 ~/.claude/skills/local-search/SKILL.md：
mkdir -p ~/.claude/skills/local-search
# 将上面的内容写入 SKILL.md
bash
重启 Claude Code 后 Skill 生效。你也可以把 Skill 文件放在项目的 .claude/skills/ 目录下，这样只对当前项目生效。
第五步：搜索结果整理与输出
Skill 定义了搜索流程，但输出质量取决于你怎么组织搜索结果。以下是三种常见的输出模式：
模式1：快速回答（搜索即回答）
适合简单事实性问题，搜索结果摘要已足够：
用户：Vue 3.5 是什么时候发布的？
AI 流程：
1. search_web("Vue 3.5 release date")
2. 从搜索摘要中提取答案
3. 直接回答 + 附来源链接
text
输出示例：
Vue 3.5 "Tengen Toppa Gurren Lagann" 于 2024年9月3日 正式发布。
主要更新包括：
- 响应式系统优化（深层响应式性能提升 56%）
- 新的 useTemplateRef() API
- 改进的 Suspense 支持
来源：[Vue 官方博客](https://blog.vuejs.org/...)
markdown
模式2：深度分析（搜索 + 爬取 + 综合）
适合技术选型、方案对比等需要深入内容的问题：
用户：帮我对比 Vite 和 Webpack 的构建性能
AI 流程：
1. search_web("Vite vs Webpack build performance 2025")
2. 评估搜索结果 → 选 5 个最相关 URL
3. crawl_url 批量爬取详细内容
4. 综合分析，生成对比表格
text
输出示例：
# Vite vs Webpack 构建性能对比
## 核心差异
| 维度 | Vite | Webpack |
|------|------|---------|
| 开发启动 | < 300ms（原生 ESM） | 10-30s（全量打包） |
| HMR 速度 | < 50ms | 1-3s |
| 生产构建 | Rollup（Tree-shaking 优秀） | 自建（插件生态丰富） |
| 配置复杂度 | 零配置起步 | 需要手动配置 |
## 建议
- 新项目优先 Vite：启动快、配置少、Vue/React 官方推荐
- 老项目用 Webpack：迁移成本高，生态插件成熟
来源：
- [Vite 官方文档](https://vite.dev/)
- [Webpack vs Vite Benchmark](https://...)
markdown
模式3：调研报告（多轮搜索 + 主题聚合）
适合竞品分析、技术调研等复杂任务：
用户：帮我调研 2025 年前端组件库的技术趋势
AI 流程：
1. 第一轮搜索：前端组件库 2025 趋势（获取全景）
2. 识别关键主题：Headless UI、Shadcn 模式、Web Components
3. 第二轮搜索：针对每个主题分别搜索
4. 爬取每个主题的 2-3 篇深度文章
5. 综合生成调研报告
text
这种模式就是 Skill 中定义的完整流程，搜索 → 爬取 → 评估 → 补充 → 输出。
完整配置检查清单
配置完成后，按这个清单逐项验证：
| 检查项 | 验证命令 | 预期结果 |
|---|---|---|
| Docker 运行中 | docker ps | grep searxng | 显示 searxng 容器 |
| SearXNG 可访问 | curl http://localhost:8080 | 返回 HTML |
| 搜索 API 可用 | curl "localhost:8080/search?q=test&format=json" | 返回 JSON |
| MCP 服务可启动 | python main.py（Ctrl+C 退出） | 无报错 |
| Claude Code 识别 MCP | 对话中调用 search_web | 返回搜索结果 |
| Skill 已加载 | 输入搜索相关问题 | AI 自动走搜索流程 |
常见问题
SearXNG 搜索不到结果
大概率是网络问题。检查代理配置：
# 进入容器检查网络
docker exec -it searxng sh
wget -q -O- https://www.google.com | head -5
# 如果超时，说明代理没配好
bash
MCP 工具不显示
- 检查
.mcp.json中的 Python 路径是否正确 - 检查 conda 环境是否安装了所有依赖
- 重启 Claude Code
crawl4ai 安装失败
crawl4ai 依赖 Playwright，需要额外安装浏览器：
pip install crawl4ai
playwright install chromium
bash
如果安装 Playwright 有问题，MCP 代码中的 fallback 会用 httpx 直接获取 HTML（没有 Markdown 转换，但能用）。
扩展：进阶功能
基础版本跑通后，可以逐步添加进阶功能：
向量搜索（语义匹配）
添加 Qdrant 向量数据库，支持"意思相近"的搜索，不限于关键词匹配：
# 在 docker-compose.yml 中取消 qdrant 的注释
docker compose up -d
bash
在 MCP 服务器中添加向量索引工具：将爬取的内容用 Embedding 模型转为向量存入 Qdrant，后续可以用语义查询检索相关内容。
全文搜索（关键词匹配）
添加 Meilisearch，支持精确的关键词搜索，比向量搜索更适合查找特定术语。
批量爬取
在 MCP 中添加 crawl_batch 工具，一次性爬取多个 URL，提升效率。
自动清理
给每次搜索创建独立的任务空间，搜索完成后自动清理数据，避免数据污染。
这些进阶功能在 local-search-mcp 开源项目中已实现，项目地址：github 搜索 local-search-mcp。
小结
搭建本地搜索系统的核心步骤：
- Docker 跑 SearXNG — 一行命令，注意代理配置
- Python 写 MCP 服务器 — 注册 search_web 和 crawl_url 两个工具
- .mcp.json 配置 Claude Code — 告诉 Claude Code 怎么启动你的 MCP
- SKILL.md 写搜索策略 — 教 AI 什么时候搜索、怎么整理结果
- 三种输出模式 — 快速回答、深度分析、调研报告，按需选择
这套系统的价值不只是搜索——它是你给 AI 装上的「眼睛」，让 AI 能自主获取实时信息，而不是只依赖训练数据。
↑